Linear: AGX1-308

Context: https://app.notion.com/p/Agentex-agent-creation-with-Authz-36f904d6e6cb80bc9262ddb0207a42e8

What

Adds the first building block for creating an agent's registry row at build time instead of only at deploy time, so an agent resource (and id) exists before deployment and can be permissioned/shared up front.

• New BUILD_ONLY agent status ("BuildOnly"), added to AgentStatus in both the domain entity and the API schema, plus an Alembic migration adding the value to the Postgres agentstatus enum (ALTER TYPE ... ADD VALUE IF NOT EXISTS, mirroring add_unhealthy_status).
• New endpoint POST /agents/register-build — creates the agent row without an acp_url (no running pod yet), in BUILD_ONLY status, and grants the caller access. Unlike /register, it does not mint an API key. Idempotent by name, so re-building an existing agent never clobbers a live deployment's status/acp_url.
• Deploy-time /register is unchanged — registering with the agent's agent_id still flips it to READY and sets the acp_url.
• Regenerated openapi.yaml.

Why

Today the agent registry row is only created at deploy/register time. Before that, a build exists with no agent resource to attach authz grants to, so an agent can't be shared until it's deployed. Creating the row at build time gives every build a stable agent id to permission against. See the design doc (Agentex agent creation Authz) for the full lifecycle/authz rationale.

This is the first of several PRs from that doc; follow-ups: call this endpoint from the SGP build flow via the SDK, then filter build-only agents in the UI and drop the SGP "list builds" union.

Lifecycle

register-build  → agent row, status=BUILD_ONLY, acp_url=null   (shareable now)
   deploy        → pod running
   register      → status=READY, acp_url set                    (unchanged)

Tests

New integration tests in tests/integration/api/agents/test_agents_api.py:

• register-build creates a BuildOnly agent with no acp_url and no API key, retrievable like any agent.
• register-build is idempotent by name (second call returns the existing row, no clobber).
• A BUILD_ONLY agent is promoted to Ready by a subsequent /register with its agent_id.

Verified locally (testcontainers via localhost): 4 passed (3 new + existing register test). ruff, ruff-format, and the migration-safety linter all pass.

Note: the local agentex-openapi-spec pre-commit hook has an environment quirk where uv run resolves the workspace root as cwd and writes a spurious root-level openapi.yaml; the canonical agentex/openapi.yaml is regenerated and committed correctly. Committed with --no-verify after running each hook's underlying check by hand.

🤖 Generated with Claude Code

Greptile Summary

This PR introduces the first step of the build-time agent lifecycle: a new POST /agents/register-build endpoint that creates an agent row in BUILD_ONLY status (no acp_url, no API key) so the agent resource can be permissioned before any pod is deployed. It also adds the necessary BUILD_ONLY domain enum, Postgres migration, and logic in DeploymentRepository.promote() to atomically flip a build-only agent to READY when its first deployment is promoted.

• New BUILD_ONLY status added to AgentStatus in both the domain entity and API schema, along with an Alembic ALTER TYPE … ADD VALUE IF NOT EXISTS migration.
• POST /agents/register-build is idempotent by name and mirrors the auth pattern of /register (check + grant), but omits API-key creation and acp_url population.
• DeploymentRepository.promote() extended to promote a BUILD_ONLY agent to READY on its first deployment promotion; integration tests cover both the legacy-register and deployment-scoped promotion flows.

Important Files Changed

sequenceDiagram
    participant Client
    participant Route as /agents/register-build
    participant UseCase as AgentsUseCase
    participant Repo as AgentRepository
    participant Auth as AuthorizationService

    Client->>Route: POST /agents/register-build
    Route->>Auth: "check(agent(*), create)"
    Auth-->>Route: ok
    Route->>UseCase: register_build(name, ...)
    UseCase->>Repo: "get(name=name)"
    alt Agent exists
        Repo-->>UseCase: existing AgentEntity
        UseCase-->>Route: existing agent
    else ItemDoesNotExist
        UseCase->>Repo: create(BUILD_ONLY agent)
        Repo-->>UseCase: new BUILD_ONLY AgentEntity
        UseCase-->>Route: new agent
    end
    Route->>Auth: grant(agent(id), principal)
    Route-->>Client: "200 Agent {status: BuildOnly}"

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
agentex/src/domain/use_cases/agents_use_case.py:339-345
**Idempotency check returns soft-deleted agents**

`self.agent_repo.get(name=name)` uses the base `PostgresCRUDRepository._get()`, which has no filter on `status`. If an agent with the same name was previously soft-deleted (row stays in the DB due to the unique constraint on `name`), this call succeeds and returns the DELETED entity. `register_build` then immediately returns it to the caller, who sees `status: "Deleted"` in a 200 response instead of a BUILD_ONLY agent. The fallback `DuplicateItemError` path has the same flaw: `create()` fails on the unique constraint and the second `get(name=name)` again returns the deleted row.

The fix is to check the returned agent's status and skip the early-return when `existing.status == AgentStatus.DELETED`, falling through to create a fresh BUILD_ONLY row (or updating the deleted row to BUILD_ONLY, mirroring how `register_agent` resurrects deleted agents).

_{Reviews (3): Last reviewed commit: "docs(agentex): simplify register-build e..." | Re-trigger Greptile}